Dateiabruf von einem SMB Share einrichten

Viele Unternehmen speichern Dokumente nicht in der Cloud, sondern auf eigenen Fileservern im Netzwerk. Mit dem SMB File Manager Agent kann 42°OS direkt auf diese Ablagestrukturen zugreifen — ohne manuelle Zwischenschritte.

SMB steht für Server Message Block — ein Netzwerkprotokoll, das Windows-Computer seit Jahrzehnten nutzen, um Dateien und Ordner im lokalen Netzwerk freizugeben. Wenn du im Windows Explorer auf ein Netzlaufwerk zugreifst (z. B. \\fileserver\dokumente), läuft das im Hintergrund über SMB.

In der Praxis begegnet dir das unter verschiedenen Namen:

Netzlaufwerk (Windows-Sprache)
Freigegebener Ordner auf einem Windows-Server
NAS-Freigabe (z. B. QNAP, Synology)
Samba-Share (Linux-Server, der SMB spricht)

Für 42°OS ist das relevant, weil viele Kunden ihre Eingangsbelege, Maschinendaten oder Exportdateien aus ERP-Systemen genau dort ablegen — nicht in einem E-Mail-Postfach, nicht in einer API, sondern schlicht als Datei in einem Netzwerkordner.

Was du vor dem ersten Workflow brauchst

Bevor du den SMB File Manager Agent verwenden kannst, müssen zwei Voraussetzungen erfüllt sein:

1. Ein Benutzer mit Zugriff auf den Share

Der SMB Share muss für einen Benutzer freigegeben sein, dessen Zugangsdaten du in 42°OS hinterlegen kannst. Das ist in der Regel ein dedizierter Service-Account — kein persönliches Benutzerkonto. Diese Einrichtung liegt auf Kundenseite und ist eine einmalige Aufgabe der IT-Abteilung.

2. Die Zugangsdaten als Credential in 42°OS

Die Verbindungsinformationen zum Share werden einmalig als Credential in 42°OS gespeichert. Im Workflow selbst referenzierst du nur den Namen dieses Credential-Eintrags — der Share-Pfad taucht im Agent nicht mehr auf.

Credentials anlegen

Navigiere in 42°OS zu Credentials und lege einen neuen Eintrag vom Typ JSON an. Der Inhalt folgt diesem Schema:

{
  "server": "fileserver.deinunternehmen.de",
  "share_name": "dokumente",
  "username": "service_account",
  "password": "sicheres_passwort"
}

Feld	Beschreibung
`server`	Hostname oder IP-Adresse des Fileservers
`share_name`	Name der Freigabe (der Ordner, der freigegeben ist)
`username`	Benutzername mit Lesezugriff auf die Freigabe
`password`	Passwort des Benutzers

Vergib dem Credential einen sprechenden Namen, z. B. smb_eingangsrechnungen. Diesen Namen trägst du später im Agent ein.

Domänen-Benutzer

Wenn der Benutzer Teil einer Windows-Domäne ist, schreibe den Benutzernamen als DOMÄNE\\benutzername — mit doppeltem Backslash.

Sonderzeichen im Passwort

Die Zeichen %, ;, ", $ und \ können in SMB-Verbindungen zu Problemen führen. Wenn möglich, verwende ein Passwort ohne diese Zeichen für den Service-Account.

Den SMB File Manager Agent konfigurieren

Der SMB File Manager Agent kann Dateien speichern, abrufen und löschen. Für den Dateiabruf verwenden wir die Aktion get.

Wichtig zu verstehen: Der Agent unterscheidet zwei Pfade:

smb_path — der Pfad zur Datei auf dem Share, relativ zum Freigabe-Stammordner
file_path — der lokale Pfad, unter dem die heruntergeladene Datei im Workflow weiterverarbeitet wird

Den Share-Ordner selbst gibst du hier nicht an — der kommt automatisch aus den Credentials.

Minimalbeispiel: eine Datei abrufen

{
  "action": "get",
  "smb_path": "eingang/rechnung-2025-001.pdf",
  "file_path": "verarbeitung/rechnung-2025-001.pdf"
}

In diesem Beispiel liegt die Datei auf dem Share unter dokumente\eingang\rechnung-2025-001.pdf — wobei dokumente der Share-Name aus den Credentials ist, den du hier nicht nochmal angibst.

Konfiguration im Agent

Option	Wert	Bedeutung
`action`	`get`	Datei vom Share herunterladen
`smb_share`	`smb_eingangsrechnungen`	Name deines Credential-Eintrags
`keep_message`	`true`	Ursprungsnachricht bleibt erhalten und wird erweitert
`allow_message_override`	`true`	Pfade können per eingehender Nachricht gesetzt werden

Vollständiger Workflow: Datei abrufen und weiterverarbeiten

Ein typischer Anwendungsfall: Ein Mitarbeiter legt eine Datei auf dem Share ab. 42°OS ruft sie ab, liest den Inhalt und leitet ihn zur Weiterverarbeitung weiter.

Manual Message Agent
      ↓
SMB File Manager Agent  (action: get)
      ↓
Read File Agent
      ↓
Generative AI Agent  (z. B. Extraktion)

Schritt 1: Manual Message Agent

Zum Testen gibst du den Dateipfad manuell vor:

{
  "smb_path": "eingang/rechnung-2025-001.pdf",
  "file_path": "verarbeitung/rechnung-2025-001.pdf"
}

Schritt 2: SMB File Manager Agent

Konfiguration:

{
  "action": "get",
  "smb_share": "smb_eingangsrechnungen",
  "smb_file_key": "smb_path",
  "file_key": "file_path",
  "keep_message": true
}

Der Agent liest smb_path und file_path aus der eingehenden Nachricht — du musst die Pfade also nicht fest in der Agent-Konfiguration verdrahten. Das macht den Workflow flexibel: verschiedene Dateien können über dieselbe Agent-Konfiguration verarbeitet werden.

Ausgabe des SMB File Manager Agent

Nach erfolgreichem Abruf sieht die Nachricht so aus:

{
  "status": "success",
  "action": "get",
  "smb_path": "eingang/rechnung-2025-001.pdf",
  "file_path": "verarbeitung/rechnung-2025-001.pdf",
  "file_size": "245KB"
}

Den Wert unter file_path verwendest du als Input-Key im nachfolgenden Read File Agent.

Dynamische Pfade mit Liquid Templating

Wenn der Dateiname nicht fest ist — z. B. weil er ein Datum oder eine Belegnummer enthält — kannst du den Pfad dynamisch zusammensetzen:

{
  "smb_path": "eingang/{{year}}/{{month}}/{{filename}}",
  "file_path": "verarbeitung/{{filename}}"
}

Oder direkt im Agent mit einem Zeitstempel:

{
  "smb_path": "exports/tagesbericht-{{ 'now' | date: '%Y-%m-%d' }}.xlsx"
}

Häufige Fehler und ihre Ursachen

Fehlermeldung	Ursache	Lösung
`NT_STATUS_LOGON_FAILURE`	Benutzername oder Passwort falsch	Credentials prüfen
`NT_STATUS_BAD_NETWORK_NAME`	Share-Name oder Server-Adresse falsch	Credential-Eintrag prüfen
`NT_STATUS_OBJECT_NAME_NOT_FOUND`	Datei unter dem angegebenen Pfad nicht vorhanden	`smb_path` prüfen, Datei muss existieren
Timeout ohne Fehlermeldung	Server nicht erreichbar oder Port 445 blockiert	Netzwerkkonnektivität und Firewall prüfen

Verbindung vorab testen

Bevor du den Workflow baust, kannst du die SMB-Verbindung mit einem einfachen Test-Workflow prüfen: Manual Message Agent → SMB File Manager Agent mit einem bekannten Pfad. Wenn "status": "success" zurückkommt, stimmen Credentials und Pfad.

Abgrenzung: SMB File Manager vs. SMB Monitor Agent

Für den Dateiabruf gibt es in 42°OS zwei Agenten — sie lösen unterschiedliche Aufgaben:

	SMB File Manager Agent	SMB Monitor Agent
Aufgabe	Einzelne Datei gezielt abrufen, speichern oder löschen	Ordner beobachten, neue Dateien erkennen
Trigger	Wird von einem vorherigen Agent angesteuert	Läuft nach Zeitplan
Output	Die Datei liegt lokal vor	Liste der neu erkannten Dateien und Ordner
Typischer Einsatz	Wenn du weißt, welche Datei du holen willst	Wenn du auf neu eintreffende Dateien reagieren willst

Für den ereignisgesteuerten Ansatz — 42°OS verarbeitet automatisch jede neue Datei, die im Eingangsordner erscheint — kombinierst du beide Agenten: der SMB Monitor Agent erkennt die neue Datei und gibt ihren Namen weiter, der SMB File Manager Agent ruft sie dann ab. Dieser Workflow ist Thema einer eigenen Lerneinheit.

Was ist ein SMB Share?​

Was du vor dem ersten Workflow brauchst​

Credentials anlegen​

Den SMB File Manager Agent konfigurieren​

Minimalbeispiel: eine Datei abrufen​

Konfiguration im Agent​

Vollständiger Workflow: Datei abrufen und weiterverarbeiten​

Schritt 1: Manual Message Agent​

Schritt 2: SMB File Manager Agent​

Ausgabe des SMB File Manager Agent​

Dynamische Pfade mit Liquid Templating​

Häufige Fehler und ihre Ursachen​

Abgrenzung: SMB File Manager vs. SMB Monitor Agent​

Was ist ein SMB Share?